sgdk: bmp.h File Reference

sgdk

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

Classes | Defines | Functions | Variables
bmp.h File Reference

Software bitmap engine. More...

`#include "maths.h"`
`#include "vdp_pal.h"`

Go to the source code of this file.

## Classes

struct | Bitmap
struct | Pixel
struct | Line
struct | Triangle

## Defines

#define | BMP_PLAN APLAN
#define | BMP_PLAN_ENUM PLAN_A
#define | BMP_PLANWIDTH_SFT 6
#define | BMP_PLANHEIGHT_SFT 6
#define | BMP_PLANWIDTH (1 << BMP_PLANWIDTH_SFT)
#define | BMP_PLANHEIGHT (1 << BMP_PLANHEIGHT_SFT)
#define | BMP_CELLWIDTH_SFT 5
#define | BMP_CELLWIDTH (1 << BMP_CELLWIDTH_SFT)
#define | BMP_CELLHEIGHT 20
#define | BMP_CELLWIDTHMASK (BMP_CELLWIDTH - 1)
#define | BMP_CELLXOFFSET (((screenWidth >> 3) - BMP_CELLWIDTH) / 2)
#define | BMP_CELLYOFFSET (((screenHeight >> 3) - BMP_CELLHEIGHT) / 2)
#define | BMP_XPIXPERTILE_SFT 3
#define | BMP_YPIXPERTILE_SFT 3
#define | BMP_XPIXPERTILE (1 << BMP_XPIXPERTILE_SFT)
#define | BMP_YPIXPERTILE (1 << BMP_YPIXPERTILE_SFT)
#define | BMP_XPIXPERTILEMASK (BMP_XPIXPERTILE - 1)
#define | BMP_YPIXPERTILEMASK (BMP_YPIXPERTILE - 1)
#define | BMP_WIDTH_SFT (BMP_CELLWIDTH_SFT + BMP_XPIXPERTILE_SFT)
#define | BMP_WIDTH (1 << BMP_WIDTH_SFT)
#define | BMP_HEIGHT (BMP_CELLHEIGHT * BMP_YPIXPERTILE)
#define | BMP_WIDTH_MASK (BMP_WIDTH - 1)
#define | BMP_PITCH_SFT (BMP_CELLWIDTH_SFT + 2)
#define | BMP_PITCH (1 << BMP_PITCH_SFT)
#define | BMP_PITCH_MASK (BMP_PITCH - 1)
#define | BMP_GENBMP16_WIDTH(genbmp16) ((genbmp16)[0])
#define | BMP_GENBMP16_HEIGHT(genbmp16) ((genbmp16)[1])
#define | BMP_GENBMP16_PALETTE(genbmp16) (&((genbmp16)[2]))
#define | BMP_GENBMP16_IMAGE(genbmp16) (&((genbmp16)[18]))
#define | BMP_GETPIXEL(x, y) bmp_buffer_write[((y) * BMP_PITCH) + ((x) >> 1)]
#define | BMP_SETPIXEL(x, y, col) bmp_buffer_write[((y) * BMP_PITCH) + ((x) >> 1)] = col;
#define | BMP_BASETILEINDEX TILE_USERINDEX
#define | BMP_FB0TILEINDEX BMP_BASETILEINDEX
#define | BMP_FB1TILEINDEX (BMP_BASETILEINDEX + (BMP_CELLWIDTH * BMP_CELLHEIGHT))
#define | BMP_FB0ENDTILEINDEX (BMP_FB0TILEINDEX + (BMP_CELLWIDTH * BMP_CELLHEIGHT))
#define | BMP_FB1ENDTILEINDEX (BMP_FB1TILEINDEX + (BMP_CELLWIDTH * BMP_CELLHEIGHT))
#define | BMP_BASETILE (BMP_BASETILEINDEX * 32)
#define | BMP_FB0TILE (BMP_FB0TILEINDEX * 32)
#define | BMP_FB1TILE (BMP_FB1TILEINDEX * 32)
#define | BMP_FB0TILEMAP_BASE BMP_PLAN
#define | BMP_FB1TILEMAP_BASE (BMP_PLAN + ((BMP_PLANWIDTH * (BMP_PLANHEIGHT / 2)) * 2))
#define | BMP_FBTILEMAP_OFFSET (((BMP_PLANWIDTH * BMP_CELLYOFFSET) + BMP_CELLXOFFSET) * 2)

## Functions

void | BMP_init (u16 double_buffer, u16 palette, u16 priority)
| Initialize the software bitmap engine.
void | BMP_end ()
| End the software bitmap engine.
void | BMP_reset ()
| Reset the software bitmap engine.
u16 | BMP_flip (u16 async)
| Flip bitmap buffer to screen.
void | BMP_clear ()
| Clear bitmap buffer.
u8 * | BMP_getWritePointer (u16 x, u16 y)
| Get write pointer for specified pixel.
u8 * | BMP_getReadPointer (u16 x, u16 y)
| Get read pointer for specified pixel.
u16 | BMP_hasFlipRequestPending ()
| Return true (!= 0) if a flip request is pending.
void | BMP_waitWhileFlipRequestPending ()
| Wait until no more flip request is pending.
u16 | BMP_hasFlipInProgess ()
| Return true (!= 0) if a flip operation is in progress.
void | BMP_waitFlipComplete ()
| Wait until the asynchronous flip operation is completed. Blit operation is the bitmap buffer transfer to VRAM.
void | BMP_drawText (const char *str, u16 x, u16 y)
| Draw text in bitmap mode.
void | BMP_clearText (u16 x, u16 y, u16 w)
| Clear text in bitmap mode.
void | BMP_clearTextLine (u16 y)
| Clear a line of text in bitmap mode.
void | BMP_showFPS (u16 float_display)
| Show the frame rate in bitmap mode.
u8 | BMP_getPixel (u16 x, u16 y)
| Get pixel at specified position.
void | BMP_setPixel (u16 x, u16 y, u8 col)
| Set pixel at specified position.
void | BMP_setPixels_V2D (const Vect2D_u16 *crd, u8 col, u16 num)
| Set pixels.
void | BMP_setPixels (const Pixel *pixels, u16 num)
| Set pixels.
u8 | BMP_clipLine (Line *l)
| Clip the specified line so it fit in bitmap screen (0, 0, BMP_WIDTH, BMP_HEIGHT)
void | BMP_drawLine (Line *l)
| Draw a line.
u16 | BMP_isPolygonCulled (const Vect2D_s16 *pts, u16 num)
| Determine if the specified polygon is culled. The polygon points should be defined in clockwise order. The method returns 1 if the polygon is back faced and should be eliminated for 3D rendering.
u16 | BMP_drawPolygon (const Vect2D_s16 *pts, u16 num, u8 col)
| Draw a polygon. The polygon points should be defined in clockwise order. Use the BMP_isPolygonCulled(..) method to test if polygon should be draw or not.
void | BMP_drawBitmapData (const u8 *data, u16 x, u16 y, u16 w, u16 h, u32 pitch)
| Draw the specified 4BPP bitmap data.
u16 | BMP_drawBitmap (const Bitmap *bitmap, u16 x, u16 y, u16 loadpal)
| Draw a Genesis Bitmap.
u16 | BMP_drawBitmapScaled (const Bitmap *bitmap, u16 x, u16 y, u16 w, u16 h, u16 loadpal)
| Load and draw a Genesis Bitmap with specified dimension.
void | BMP_loadBitmapData (const u8 *data, u16 x, u16 y, u16 w, u16 h, u32 pitch)
void | BMP_loadBitmap (const Bitmap *bitmap, u16 x, u16 y, u16 loadpal)
void | BMP_loadAndScaleBitmap (const Bitmap *bitmap, u16 x, u16 y, u16 w, u16 h, u16 loadpal)
void | BMP_getBitmapPalette (const Bitmap *bitmap, u16 *pal)
void | BMP_scale (const u8 *src_buf, u16 src_wb, u16 src_h, u16 src_pitch, u8 *dst_buf, u16 dst_wb, u16 dst_h, u16 dst_pitch)
| Scale the specified source bitmap image to specified dimension.

## Variables

u8 * | bmp_buffer_read
u8 * | bmp_buffer_write

## Detailed Description

Software bitmap engine.

Author:
  Stephane Dallongeville

Date:
  08/2011

This unit provides methods to simulate bitmap mode on SEGA genesis.
The software bitmap engine permit to simulate a 256x160 pixels bitmap screen.
Almost methods as BMP_setPixel and BMP_drawLine however use doubled X pixel so you can consider resolution to be 128x160 in this case.
It uses a double buffer so you can draw to buffer while other buffer is being sent to video memory.
Bitmap buffer requires ~41 KB of memory which is dynamically allocated.
These buffers are transfered to VRAM during blank area, by default on NTSC system the blanking period
is very short so it takes approximately 10 frames to blit an entire buffer.
To improve transfer performance the blank area is extended to fit bitmap resolution:
0-31 = blank
32-191 = active
192-262/312 = blank
With extended blank bitmap can be transfered to VRAM 20 times per second in NTSC
and 25 time per second in PAL.

## Define Documentation

#define BMP_CELLHEIGHT 20

Bitmap height (in tile) : 20

#define BMP_CELLWIDTH (1 << BMP_CELLWIDTH_SFT)

Bitmap width (in tile) : 32

#define BMP_GENBMP16_HEIGHT | ( |  | genbmp16 | ) | ((genbmp16)[1])

Get height of genesis bitmap 16 object.

#define BMP_GENBMP16_IMAGE | ( |  | genbmp16 | ) | (&((genbmp16)[18]))

Return pointer to image data of genesis bitmap 16 object.

#define BMP_GENBMP16_PALETTE | ( |  | genbmp16 | ) | (&((genbmp16)[2]))

Return pointer to palette of genesis bitmap 16 object.

#define BMP_GENBMP16_WIDTH | ( |  | genbmp16 | ) | ((genbmp16)[0])

Get width of genesis bitmap 16 object.

#define BMP_GETPIXEL | ( |  | x,
|  |  | y
| ) |  | bmp_buffer_write[((y) * BMP_PITCH) + ((x) >> 1)]

Return pixel value at specified location.

Parameters:

  x | X coordinate.
  y | Y coordinate.

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_GETPIXEL(0,0) will actually returns same value as BMP_GETPIXEL((1,0)
Be careful this function does not check for retrieving pixel outside bitmap buffer.

#define BMP_HEIGHT (BMP_CELLHEIGHT * BMP_YPIXPERTILE)

Bitmap height (in pixel) : 160

#define BMP_PITCH (1 << BMP_PITCH_SFT)

Bitmap scanline pitch (number of bytes per scanline) : 128

#define BMP_PLAN APLAN

Plan used to draw bitmap (plan A).

#define BMP_PLANHEIGHT (1 << BMP_PLANHEIGHT_SFT)

Bitmap plan height (in tile) : 64

#define BMP_PLANWIDTH (1 << BMP_PLANWIDTH_SFT)

Bitmap plan width (in tile) : 64

#define BMP_SETPIXEL | ( |  | x,
|  |  | y,
|  |  | col
| ) |  | bmp_buffer_write[((y) * BMP_PITCH) + ((x) >> 1)] = col;

Set pixel value at specified position.

Parameters:

  x | X pixel coordinate.
  y | Y pixel coordinate.
  col | pixel color.

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_SETPIXEL(0,0,..) will actually set same pixel as BMP_SETPIXEL(1,0,..). Be careful this function does not check for retrieving pixel outside bitmap buffer.

#define BMP_WIDTH (1 << BMP_WIDTH_SFT)

Bitmap width (in pixel) : 256

#define BMP_XPIXPERTILE (1 << BMP_XPIXPERTILE_SFT)

Number of X pixel per tile : 8 pixels per tile.

#define BMP_YPIXPERTILE (1 << BMP_YPIXPERTILE_SFT)

Number of y pixel per tile : 8 pixels per tile.

## Function Documentation

void BMP_clearText | ( | u16 | x,
|  | u16 | y,
|  | u16 | w
| ) |  |

Clear text in bitmap mode.

Parameters:

  x | X coordinate (in tile).
  y | y coordinate (in tile).
  w | Number of characters to clear.

void BMP_clearTextLine | ( | u16 | y | ) |

Clear a line of text in bitmap mode.

Parameters:

  y | y coordinate (in tile).

u8 BMP_clipLine | ( | Line * | l | ) |

Clip the specified line so it fit in bitmap screen (0, 0, BMP_WIDTH, BMP_HEIGHT)

Parameters:

  l | Line to clip.

Returns:
  false (0) is the line is entirely outside bitmap screen.
  true if at least one pixel is on screen.

u16 BMP_drawBitmap | ( | const Bitmap * | bitmap,
|  | u16 | x,
|  | u16 | y,
|  | u16 | loadpal
| ) |  |

Draw a Genesis Bitmap.

A Genesis bitmap is automatically created from .bmp or .png file via the rescomp tool.
The resulting file contains bitmap size info and 16 colors palette.

Parameters:

  bitmap | Genesis Bitmap. The Bitmap is unpacked "on the fly" if needed (require some memory).
  x | X coordinate (should be an even value).
  y | y coordinate.
  loadpal | Load the bitmap palette information when non zero.

Returns:
  FALSE if there is not enough memory to unpack the specified Bitmap (only if compression was enabled).

X coordinate is aligned to even value for performance reason.
So BMP_drawBitmap(bitmap,0,0,TRUE) will produce same result as BMP_drawBitmap(bitmap,1,0,TRUE)

void BMP_drawBitmapData | ( | const u8 * | data,
|  | u16 | x,
|  | u16 | y,
|  | u16 | w,
|  | u16 | h,
|  | u32 | pitch
| ) |  |

Draw the specified 4BPP bitmap data.

Parameters:

  data | 4BPP image data buffer.
  x | X coordinate (should be an even value for byte alignment).
  y | y coordinate.
  w | width (should be an even value for byte alignment).
  h | height.
  pitch | bitmap pitch (number of bytes per bitmap scanline).

X coordinate as Width are aligned to even value for performance reason.
So BMP_drawBitmapData(data,0,0,w,h,w) will produce same result as BMP_drawBitmapData(data,1,0,w,h,w)

u16 BMP_drawBitmapScaled | ( | const Bitmap * | bitmap,
|  | u16 | x,
|  | u16 | y,
|  | u16 | w,
|  | u16 | h,
|  | u16 | loadpal
| ) |  |

Load and draw a Genesis Bitmap with specified dimension.

A Genesis bitmap is automatically created from .bmp or .png file via the rescomp tool.
The resulting file contains bitmap size info and 16 colors palette.
This method will scale and draw the bitmap with the specified dimension.

Parameters:

  bitmap | Genesis bitmap. The Bitmap is unpacked "on the fly" if needed (require some memory).
  x | X coordinate (should be an even value).
  y | y coordinate.
  w | final width.
  h | final height.
  loadpal | Load the bitmap palette information when non zero.

Returns:
  FALSE if there is not enough memory to unpack the specified Bitmap (only if compression was enabled).

X coordinate as width are aligned to even values for performance reason.
So BMP_drawBitmapScaled(bitmap,0,0,w,h,pal) will produce same result as BMP_drawBitmapScaled(bitmap,1,0,w,h,pal)

void BMP_drawLine | ( | Line * | l | ) |

Draw a line.

Parameters:

  l | Line to draw.

Lines are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_drawLine(0,0,0,159) will actually draw same line as BMP_drawLine(1,0,1,159).

u16 BMP_drawPolygon | ( | const Vect2D_s16 * | pts,
|  | u16 | num,
|  | u8 | col
| ) |  |

Draw a polygon.
The polygon points should be defined in clockwise order.
Use the BMP_isPolygonCulled(..) method to test if polygon should be draw or not.

Parameters:

  pts | Polygon points buffer.
  num | number of point (lenght of points buffer).
  col | fill color.

Returns:
  0 if polygon was not drawn (outside screen or whatever).

void BMP_drawText | ( | const char * | str,
|  | u16 | x,
|  | u16 | y
| ) |  |

Draw text in bitmap mode.

Parameters:

  str | String to display.
  x | X coordinate (in tile).
  y | y coordinate (in tile).

void BMP_end | ( |  | ) |

End the software bitmap engine.

Release memory used by software bitmap engine (~41 KB).

u16 BMP_flip | ( | u16 | async | ) |

Flip bitmap buffer to screen.

Blit the current bitmap back buffer to the screen then flip buffers so back buffer becomes front buffer and vice versa.
If you use async flag the Bitmap buffer will be sent to video memory asynchronously during blank period and the function return immediatly.
If a flip is already in process then flip request is marked as pending and will be processed as soon the current one complete.
You can use BMP_waitWhileFlipRequestPending() method to ensure no more flip request are pending before writing to bitmap buffer.
If a flip request is already pending the function wait until no more request are pending.

Parameters:

  async | Asynchronous flip operation flag.

Returns:
  Only meaningful for async operation:
  0 if the flip request has be marked as pending as another flip is already in process.
  1 if the flip request has be initiated.

See also:
  BMP_hasFlipRequestPending()
  BMP_waitWhileFlipRequestPending()

void BMP_getBitmapPalette | ( | const Bitmap * | bitmap,
|  | u16 * | pal
| ) |  |

Deprecated:
  Uses bitmap->palette instead.

u8 BMP_getPixel | ( | u16 | x,
|  | u16 | y
| ) |  |

Get pixel at specified position.

Parameters:

  x | X coordinate.
  y | Y coordinate.

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_getPixel(0,0) will actually returns same value as BMP_getPixel(1,0).

See also:
  BMP_GETPIXEL (faster but not as safe)

u8* BMP_getReadPointer | ( | u16 | x,
|  | u16 | y
| ) |  |

Get read pointer for specified pixel.

Parameters:

  x | X pixel coordinate.
  y | Y pixel coordinate.

As coordinates are expressed for 4bpp pixel BMP_getReadPointer(0,0) and BMP_getReadPointer(1,0) actually returns the same address.

u8* BMP_getWritePointer | ( | u16 | x,
|  | u16 | y
| ) |  |

Get write pointer for specified pixel.

Parameters:

  x | X pixel coordinate.
  y | Y pixel coordinate.

As coordinates are expressed for 4bpp pixel BMP_getWritePointer(0,0) and BMP_getWritePointer(1,0) actually returns the same address.

void BMP_init | ( | u16 | double_buffer,
|  | u16 | palette,
|  | u16 | priority
| ) |  |

Initialize the software bitmap engine.

Parameters:

  double_buffer | Enabled VRAM double buffer. VRAM Double buffer permit to avoid image tearing because of partial screen refresh. It requires almost all VRAM tiles space (~41 KB) so enable it only if you don't need other plan or sprites.
  palette | Palette index to use to render the bitmap plan. Set it to 0 if unsure.
  priority | Set the priority of bitmap plan. 0 = low priority (default). 1 = high priority.

Requires ~41 KB of memory which is dynamically allocated.

u16 BMP_isPolygonCulled | ( | const Vect2D_s16 * | pts,
|  | u16 | num
| ) |  |

Determine if the specified polygon is culled.
The polygon points should be defined in clockwise order.
The method returns 1 if the polygon is back faced and should be eliminated for 3D rendering.

Parameters:

  pts | Polygon points buffer.
  num | number of point (lenght of points buffer).

Returns:
  1 if polygon is culled (should not be draw) and 0 otherwise.

void BMP_loadAndScaleBitmap | ( | const Bitmap * | bitmap,
|  | u16 | x,
|  | u16 | y,
|  | u16 | w,
|  | u16 | h,
|  | u16 | loadpal
| ) |  |

Deprecated:
  Use BMP_drawBitmapEx(..) instead.

void BMP_loadBitmap | ( | const Bitmap * | bitmap,
|  | u16 | x,
|  | u16 | y,
|  | u16 | loadpal
| ) |  |

Deprecated:
  Use BMP_drawBitmap(..) instead.

void BMP_loadBitmapData | ( | const u8 * | data,
|  | u16 | x,
|  | u16 | y,
|  | u16 | w,
|  | u16 | h,
|  | u32 | pitch
| ) |  |

Deprecated:
  Use BMP_drawBitmapData(..) instead.

void BMP_reset | ( |  | ) |

Reset the software bitmap engine.

Rebuild tilemap for bitmap engine and clear buffers.

void BMP_scale | ( | const u8 * | src_buf,
|  | u16 | src_wb,
|  | u16 | src_h,
|  | u16 | src_pitch,
|  | u8 * | dst_buf,
|  | u16 | dst_wb,
|  | u16 | dst_h,
|  | u16 | dst_pitch
| ) |  |

Scale the specified source bitmap image to specified dimension.

Take a source bitmap with its specified dimension and scale it in the
destination buffer with specified dimension.

Parameters:

  src_buf | source bitmap buffer.
  src_wb | source width in byte.
  src_h | source height.
  src_pitch | source pitch (number of bytes per scanline).
  dst_buf | destination bitmap buffer.
  dst_wb | destination width in byte.
  dst_h | destination height.
  dst_pitch | destination pitch (number of bytes per scanline).

void BMP_setPixel | ( | u16 | x,
|  | u16 | y,
|  | u8 | col
| ) |  |

Set pixel at specified position.

Parameters:

  x | X pixel coordinate.
  y | Y pixel coordinate.
  col | pixel color.

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_setPixel(0,0,..) will actually set same pixel as BMP_setPixel(1,0,..).

See also:
  BMP_SETPIXEL (faster but not as safe)

void BMP_setPixels | ( | const Pixel * | pixels,
|  | u16 | num
| ) |  |

Set pixels.

Parameters:

  pixels | Pixels buffer.
  num | number of pixel to draw (lenght of pixels buffer).

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_setPixel(0,0,..) will actually set same pixel as BMP_setPixel(1,0,..).

void BMP_setPixels_V2D | ( | const Vect2D_u16 * | crd,
|  | u8 | col,
|  | u16 | num
| ) |  |

Set pixels.

Parameters:

  crd | Coordinates buffer.
  col | pixels color.
  num | number of pixel to draw (lenght of coordinates buffer).

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_setPixel(0,0,..) will actually set same pixel as BMP_setPixel(1,0,..).

void BMP_showFPS | ( | u16 | float_display | ) |

Show the frame rate in bitmap mode.

Parameters:

  float_display | If this value is true (!= 0) the frame rate is displayed as float (else it's integer).

## Variable Documentation

u8* bmp_buffer_read

Current bitmap read buffer.

u8* bmp_buffer_write

Current bitmap write buffer.

All Classes Files Functions Variables Typedefs Enumerations Defines